/**
 * Licensed under the MIT License
 *
 * Copyright (c) 2010 Benoit Saint-Maxent
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 */
package marcel.controller.command {
	import flash.events.IEventDispatcher;

	/**
	 * @eventType marcel.events.AsyncRequestEvent.PROGRESS
	 */
	[Event(name = "progress", type = "marcel.events.AsyncRequestEvent")]
	 
	/**
	 * @eventType marcel.events.AsyncRequestEvent.FAULT
	 */
	[Event(name = "fault", type = "marcel.events.AsyncRequestEvent")]
	
	/**
	 * @eventType marcel.events.AsyncRequestEvent.RESULT
	 */
	[Event(name = "result", type = "marcel.events.AsyncRequestEvent")]

	/**
	 * IAsyncCommand is a ICommand that needs time to execute its request.
	 * It dispatches an event to notify progress, failure or success of its process.
	 *  
	 * @author Benoit Saint-Maxent
	 */
	public interface IAsyncCommand extends ICommand, IEventDispatcher {
		
		/**
		 * Returns the weight property of the current IAsyncCommand
		 * Useful only if the current IAsyncCommand is part of an IMacroCommand stack
		 * @return	The weight property of the current IAsyncCommand
		 */
		function get weight() : uint;
		
		/**
		 * Sets the weight property of the current IAsyncCommand
		 * Useful only if the current IAsyncCommand is part of an IMacroCommand stack
		 */
		function set weight(n : uint) : void;
		
		/**
		 * Returns the maximum number of attempts to run the query, in case of failure
		 * @return	The maximum number of attempts to run the query, in case of failure
		 */
		function get numMaxAttempts() : uint;
		
		/**
		 * Sets the maximum number of attempts to run the query, in case of failure
		 */
		function set numMaxAttempts(n : uint) : void;
		
		/**
		 * Returns the percentage of completion of the current process (0 -> 1)
		 * @return	The percentage of completion of the current process (0 -> 1)
		 */
		function get percentProgress() : Number;
		
		/**
		 * Dispatches a AsyncRequestEvent.PROGRESS event
		 * and sets the percent value of the event
		 * with percentProgress property
		 */
		function notifyProgress() : void;
		
		/**
		 * Dispatches a AsyncRequestEvent.FAULT event
		 * with the passed-in CoreError
		 */
		function notifyFault(error : Error = null) : void;
		
		/**
		 * Dispatches a AsyncRequestEvent.RESULT event
		 * with the passed-in result
		 */
		function notifyResult(result : * = null) : void;
		
		/**
		 * Returns true if the current IAsyncCommand is actually processing
		 * @return	true if the current IAsyncCommand is actually processing
		 */
		function get isProcessing() : Boolean;

		/**
		 * Prepares the current IAsyncCommand to be removed from memory
		 */
		function kill() : void;
	}
}
